<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>AppArmor</title>
<link rel="stylesheet" type="text/css" href="../C.css">
<script type="text/javascript" src="../jquery.js"></script><script type="text/javascript" src="../jquery.syntax.js"></script><script type="text/javascript" src="../yelp.js"></script>
</head>
<body id="home">
<!--<script src="https://ssl.google-analytics.com/urchin.js" type="text/javascript"></script><script type="text/javascript">
        _uacct = "UA-1018242-8";
        urchinTracker();
      </script><script>
      function englishPageVersion() {
        var href = window.location.href;
        if (href.slice(-1) == "/") {
                window.location = "index.html.en";
        } else {
                window.location = href.replace(/\.html.*/, ".html.en");
        }
         return false;
      }
      function browserPreferredLanguage() {
        var href = window.location.href;
        if (href.slice(-1) == "/") {
                window.location = href;
        } else {
                window.location = href.replace(/\.html.*/, ".html");
        }
        return false;
      }
      </script>--><div id="container">
<div id="container-inner">
<div id="mothership"><ul>
<li><a href="https://partners.ubuntu.com">Partners</a></li>
<li><a href="https://www.ubuntu.com/support/community-support">Support</a></li>
<li><a href="https://community.ubuntu.com">Community</a></li>
<li><a href="https://www.ubuntu.com">Ubuntu.com</a></li>
</ul></div>
<div id="header">
<h1 id="ubuntu-header"><a href="https://help.ubuntu.com/">Ubuntu Documentation</a></h1>
<ul id="main-menu">
<li><a class="main-menu-item current" href="https://help.ubuntu.com/">Official Documentation</a></li>
<li><a href="https://help.ubuntu.com/community/CommunityHelpWiki">Community Help Wiki</a></li>
<li><a href="https://community.ubuntu.com/t/contribute/26">Contribute</a></li>
</ul>
</div>
<div id="menu-search"><div id="search-box">
<noscript><form action="https://www.google.com/cse" id="cse-search-box"><div>
<input type="hidden" name="cx" value="003883529982892832976:e2vwumte3fq"><input type="hidden" name="ie" value="UTF-8"><input type="text" name="q" size="21"><input type="submit" name="sa" value="Search">
</div></form></noscript><!--
<script>
                document.write('<form action="https://help.ubuntu.com/search.html" id="cse-search-box">');
                document.write('  <div>');
                document.write('    <input type="hidden" name="cof" value="FORID:9">');
                document.write('    <input type="hidden" name="cx" value="003883529982892832976:e2vwumte3fq">');
                document.write('    <input type="hidden" name="ie" value="UTF-8">');
                document.write('    <input type="text" name="q" size="21">');
                document.write('    <input type="submit" name="sa" value="Search">');
                document.write('  </div>');
                document.write('</form>');
              </script>-->
</div></div>
<div class="trails"><div class="trail">
<a href="https://help.ubuntu.com/18.04" class="trail">Ubuntu 18.04</a> » <a class="trail" href="../index.html" title="Ubuntu Server Guide">Ubuntu Server Guide</a> » <a class="trail" href="security.html" title="Security">Security</a> » </div></div>
<div id="cwt-content" class="clearfix content-area"><div id="page">
<div id="content">
<div class="links nextlinks">
<a class="nextlinks-prev" href="firewall.html" title="Firewall">Previous</a><a class="nextlinks-next" href="certificates-and-security.html" title="Certificates">Next</a>
</div>
<div class="hgroup"><h1 class="title">AppArmor</h1></div>
<div class="region">
<div class="contents">
<p class="para">
	  <span class="app application">AppArmor</span> is a Linux Security Module implementation of name-based mandatory access controls.   
	  AppArmor confines individual programs to a set of listed files and posix 1003.1e draft capabilities.
	  </p>
<p class="para">
	  <span class="app application">AppArmor</span> is installed and loaded by default. It uses <span class="em emphasis">profiles</span> of 
	  an application to determine what files and permissions the application requires. Some packages will install their own profiles,  
          and additional profiles can be found in the <span class="app application">apparmor-profiles</span> package.
	  </p>
<p class="para">
	  To install the <span class="app application">apparmor-profiles</span> package from a terminal prompt:
	  </p>
<div class="screen"><pre class="contents "><span class="cmd command">sudo apt install apparmor-profiles</span>
</pre></div>
<p class="para">
	  AppArmor profiles have two modes of execution:
	  </p>
<div class="list itemizedlist"><ul class="list itemizedlist">
<li class="list itemizedlist">
	      <p class="para">
	      Complaining/Learning: profile violations are permitted and logged. Useful for testing and developing new profiles.
	      </p>
	    </li>
<li class="list itemizedlist">
	      <p class="para">
	      Enforced/Confined: enforces profile policy as well as logging the violation.
	      </p>
	    </li>
</ul></div>
</div>
<div class="links sectionlinks" role="navigation"><ul>
<li class="links"><a class="xref" href="apparmor.html#apparmor-usage" title="Using AppArmor">Using AppArmor</a></li>
<li class="links"><a class="xref" href="apparmor.html#apparmor-profiles" title="Profiles">Profiles</a></li>
<li class="links"><a class="xref" href="apparmor.html#apparmor-references" title="References">References</a></li>
</ul></div>
<div class="sect2 sect" id="apparmor-usage"><div class="inner">
<div class="hgroup"><h2 class="title">Using AppArmor</h2></div>
<div class="region"><div class="contents">
<div class="note note-warning" title="Warning"><div class="inner"><div class="region"><div class="contents">
   		  <p class="para">
   		  This section is plagued by a bug (<a href="https://bugs.launchpad.net/ubuntu/+source/apparmor/+bug/1304134" class="ulink" title="https://bugs.launchpad.net/ubuntu/+source/apparmor/+bug/1304134">LP #1304134</a>) 
		  and instructions will not work as advertised.
   		  </p>
	       </div></div></div></div>
<p class="para">
	    The <span class="app application">apparmor-utils</span> package contains command line utilities that you can use to change the
	    <span class="app application">AppArmor</span> execution mode, find the status of a profile, create new profiles, etc.
	    </p>
<div class="list itemizedlist"><ul class="list itemizedlist">
<li class="list itemizedlist">
	    	<p class="para">
	    	<span class="app application">apparmor_status</span> is used to view the current status of AppArmor profiles.
	    	</p>
<div class="screen"><pre class="contents "><span class="cmd command">sudo apparmor_status</span>
</pre></div>
	      </li>
<li class="list itemizedlist">
	        <p class="para">
		<span class="app application">aa-complain</span> places a profile into <span class="em emphasis">complain</span> mode.
		</p>
<div class="screen"><pre class="contents "><span class="cmd command">sudo aa-complain /path/to/bin</span>
</pre></div>
	      </li>
<li class="list itemizedlist">
	        <p class="para">
		<span class="app application">aa-enforce</span> places a profile into <span class="em emphasis">enforce</span> mode.
		</p>
<div class="screen"><pre class="contents "><span class="cmd command">sudo aa-enforce /path/to/bin</span>
</pre></div>
	      </li>
<li class="list itemizedlist">
	    	<p class="para">
	   	The <span class="file filename">/etc/apparmor.d</span> directory is where the AppArmor profiles are located. It can be used to 
	    	manipulate the <span class="em emphasis">mode</span> of all profiles.
	    	</p>
	    	<p class="para">
	    	Enter the following to place all profiles into complain mode:
	    	</p>
<div class="screen"><pre class="contents "><span class="cmd command">sudo aa-complain /etc/apparmor.d/*</span>
</pre></div>
	    <p class="para">
	    To place all profiles in enforce mode:
	    </p>
<div class="screen"><pre class="contents "><span class="cmd command">sudo aa-enforce /etc/apparmor.d/*</span>
</pre></div>
	      </li>
<li class="list itemizedlist">
	        <p class="para">
		<span class="app application">apparmor_parser</span> is used to load a profile into the kernel. It can also be used to 
	        reload a currently loaded profile using the <span class="em emphasis">-r</span> option. To load a profile:
		</p>
<div class="screen"><pre class="contents "><span class="cmd command">cat /etc/apparmor.d/profile.name | sudo apparmor_parser -a</span>
</pre></div>
		<p class="para">
		To reload a profile:
		</p>
<div class="screen"><pre class="contents "><span class="cmd command">cat /etc/apparmor.d/profile.name | sudo apparmor_parser -r</span>
</pre></div>
	      </li>
<li class="list itemizedlist">
	   	<p class="para">
	   	<span class="file filename">systemctl</span> can be used to <span class="em emphasis">reload</span> all profiles:
	   	</p>
<div class="screen"><pre class="contents "><span class="cmd command">sudo systemctl reload apparmor.service</span>
</pre></div>
	      </li>
<li class="list itemizedlist">
	    	<p class="para">
	    	The <span class="file filename">/etc/apparmor.d/disable</span> directory can be used along with the <span class="app application">apparmor_parser -R</span> 
		option to <span class="em emphasis">disable</span> a profile.
	    	</p>
<div class="screen"><pre class="contents "><span class="cmd command">sudo ln -s /etc/apparmor.d/profile.name /etc/apparmor.d/disable/</span>
<span class="cmd command">sudo apparmor_parser -R /etc/apparmor.d/profile.name</span>
</pre></div>
	        <p class="para">
		To <span class="em emphasis">re-enable</span> a disabled profile remove the symbolic link to the profile in 
		<span class="file filename">/etc/apparmor.d/disable/</span>. Then load the profile using the <span class="em emphasis">-a</span> option.
		</p>
<div class="screen"><pre class="contents "><span class="cmd command">sudo rm /etc/apparmor.d/disable/profile.name</span>
<span class="cmd command">cat /etc/apparmor.d/profile.name | sudo apparmor_parser -a</span>
</pre></div>
	      </li>
<li class="list itemizedlist">
	    	<p class="para">
	    	<span class="app application">AppArmor</span> can be disabled, and the kernel module unloaded by entering the following:
	    	</p>
<div class="screen"><pre class="contents "><span class="cmd command">sudo systemctl stop apparmor.service</span>
<span class="cmd command">sudo update-rc.d -f apparmor remove</span>
</pre></div>
	      </li>
<li class="list itemizedlist">
	        <p class="para">
	   	To re-enable <span class="app application">AppArmor</span> enter:
		</p>
<div class="screen"><pre class="contents "><span class="cmd command">sudo systemctl start apparmor.service</span>
<span class="cmd command">sudo update-rc.d apparmor defaults</span>
</pre></div>
	      </li>
</ul></div>
<div class="note" title="Note"><div class="inner"><div class="region"><div class="contents">
	      <p class="para">
	      Replace <span class="em emphasis">profile.name</span> with the name of the profile you want to manipulate. Also, replace 
	      <span class="file filename">/path/to/bin/</span> with the actual executable file path. For example for the <span class="app application">ping</span> 
	      command use <span class="file filename">/bin/ping</span>
	      </p>
	    </div></div></div></div>
</div></div>
</div></div>
<div class="sect2 sect" id="apparmor-profiles"><div class="inner">
<div class="hgroup"><h2 class="title">Profiles</h2></div>
<div class="region">
<div class="contents">
<p class="para">
	    <span class="app application">AppArmor</span> profiles are simple text files located in <span class="file filename">/etc/apparmor.d/</span>. The 
	    files are named after the full path to the executable they profile replacing the "/" with ".".
	    For example <span class="file filename">/etc/apparmor.d/bin.ping</span> is the AppArmor profile for the <span class="file filename">/bin/ping</span>
	    command.  
	    </p>
<p class="para">
 	    There are two main type of rules used in profiles:
	    </p>
<div class="list itemizedlist"><ul class="list itemizedlist">
<li class="list itemizedlist">
	        <p class="para">
	        <span class="em emphasis">Path entries:</span> detail which files an application can access in the file system.
	        </p>
	      </li>
<li class="list itemizedlist">
	        <p class="para">
	        <span class="em emphasis">Capability entries:</span> determine what privileges a confined process is allowed to use.
	        </p>
	      </li>
</ul></div>
<p class="para">
	    As an example, take a look at <span class="file filename">/etc/apparmor.d/bin.ping</span>:
	    </p>
<div class="code"><pre class="contents ">#include &lt;tunables/global&gt;
/bin/ping flags=(complain) {
  #include &lt;abstractions/base&gt;
  #include &lt;abstractions/consoles&gt;
  #include &lt;abstractions/nameservice&gt;

  capability net_raw,
  capability setuid,
  network inet raw,
  
  /bin/ping mixr,
  /etc/modules.conf r,
}
</pre></div>
<div class="list itemizedlist"><ul class="list itemizedlist">
<li class="list itemizedlist">
	        <p class="para">
		<span class="em emphasis">#include &lt;tunables/global&gt;:</span> include statements from other files. This allows statements pertaining to 
	        multiple applications to be placed in a common file.
	        </p>
	      </li>
<li class="list itemizedlist">
	        <p class="para">
		<span class="em emphasis">/bin/ping flags=(complain):</span> path to the profiled program, also setting the mode to 
	        <span class="em emphasis">complain</span>.
	        </p>
	      </li>
<li class="list itemizedlist">
	        <p class="para">
		<span class="em emphasis">capability net_raw,:</span> allows the application access to the CAP_NET_RAW Posix.1e capability.
	        </p>
	      </li>
<li class="list itemizedlist">
	        <p class="para">
		<span class="em emphasis">/bin/ping mixr,:</span> allows the application read and execute access to the file.
	        </p>
	      </li>
</ul></div>
<div class="note" title="Note"><div class="inner"><div class="region"><div class="contents">
	      <p class="para">
	      After editing a profile file the profile must be reloaded. See <a class="xref" href="apparmor.html#apparmor-usage" title="Using AppArmor">Using AppArmor</a> for details.
	      </p>
	    </div></div></div></div>
</div>
<div class="sect3 sect" id="apparmor-profiles-new"><div class="inner">
<div class="hgroup"><h3 class="title">Creating a Profile</h3></div>
<div class="region"><div class="contents"><div class="list itemizedlist"><ul class="list itemizedlist">
<li class="list itemizedlist">
	          <p class="para">
	       	  <span class="em emphasis">Design a test plan:</span> Try to think about how the application should be exercised. The test plan should be divided 
	          into small test cases. Each test case should have a small description and list the steps to follow.
	          </p>
		  <p class="para">
		  Some standard test cases are:
	          </p>
	          <div class="list itemizedlist"><ul class="list itemizedlist">
<li class="list itemizedlist">		
		      <p class="para">
	              Starting the program.
    		      </p>
		    </li>
<li class="list itemizedlist">		
		      <p class="para">
      		      Stopping the program.
    		      </p>
		    </li>
<li class="list itemizedlist">		
		      <p class="para">
      		      Reloading the program.
    		      </p>
		    </li>
<li class="list itemizedlist">		
		      <p class="para">
      	              Testing all the commands supported by the init script.
    		      </p>
		    </li>
</ul></div>
		</li>
<li class="list itemizedlist">
	          <p class="para">
		  <span class="em emphasis">Generate the new profile:</span> Use <span class="app application">aa-genprof</span> to generate a new profile.
		  From a terminal:
		  </p>
<div class="screen"><pre class="contents "><span class="cmd command">sudo aa-genprof executable</span>
</pre></div>
		    <p class="para">
		    For example:
		    </p>
<div class="screen"><pre class="contents "><span class="cmd command">sudo aa-genprof slapd</span>
</pre></div>
		</li>
<li class="list itemizedlist">
		  <p class="para">
		  To get your new profile included in the <span class="app application">apparmor-profiles</span> package, file a bug in 
		  <span class="em emphasis">Launchpad</span> against the <a href="https://bugs.launchpad.net/ubuntu/+source/apparmor/+filebug" class="ulink" title="https://bugs.launchpad.net/ubuntu/+source/apparmor/+filebug">AppArmor</a> 
		  package:
		  </p>
		  <div class="list itemizedlist"><ul class="list itemizedlist">
<li class="list itemizedlist">
		      <p class="para">
		      Include your test plan and test cases.
  		      </p>
		    </li>
<li class="list itemizedlist">
		      <p class="para">
		      Attach your new profile to the bug.
		      </p>
		    </li>
</ul></div>
		</li>
</ul></div></div></div>
</div></div>
<div class="sect3 sect" id="apparmor-profiles-update"><div class="inner">
<div class="hgroup"><h3 class="title">Updating Profiles</h3></div>
<div class="region"><div class="contents">
<p class="para">
	      When the program is misbehaving, audit messages are sent to the log files. The program <span class="app application">aa-logprof</span> can be used 
	      to scan log files for <span class="app application">AppArmor</span> audit messages, review them and update the profiles. From a terminal:
	      </p>
<div class="screen"><pre class="contents "><span class="cmd command">sudo aa-logprof</span>
</pre></div>
</div></div>
</div></div>
</div>
</div></div>
<div class="sect2 sect" id="apparmor-references"><div class="inner">
<div class="hgroup"><h2 class="title">References</h2></div>
<div class="region"><div class="contents">
<div class="list itemizedlist"><ul class="list itemizedlist"><li class="list itemizedlist">
	        <p class="para">
		See the <a href="http://www.novell.com/documentation/apparmor/apparmor201_sp10_admin/index.html?page=/documentation/apparmor/apparmor201_sp10_admin/data/book_apparmor_admin.html" class="ulink" title="http://www.novell.com/documentation/apparmor/apparmor201_sp10_admin/index.html?page=/documentation/apparmor/apparmor201_sp10_admin/data/book_apparmor_admin.html">AppArmor Administration Guide</a> for advanced configuration options.
  	        </p>
	      </li></ul></div>
<div class="list itemizedlist"><ul class="list itemizedlist"><li class="list itemizedlist">
	        <p class="para">
	        For details using AppArmor with other Ubuntu releases see the <a href="https://help.ubuntu.com/community/AppArmor" class="ulink" title="https://help.ubuntu.com/community/AppArmor">
		AppArmor Community Wiki</a> page.
  	        </p>
	      </li></ul></div>
<div class="list itemizedlist"><ul class="list itemizedlist"><li class="list itemizedlist">
	        <p class="para">
		The <a href="http://en.opensuse.org/SDB:AppArmor_geeks" class="ulink" title="http://en.opensuse.org/SDB:AppArmor_geeks">OpenSUSE AppArmor</a> page is another introduction to AppArmor.
  	        </p>
	      </li></ul></div>
<div class="list itemizedlist"><ul class="list itemizedlist"><li class="list itemizedlist">
	  	<p class="para">
		A great place to ask for <span class="app application">AppArmor</span> assistance, and get involved with the Ubuntu Server community, 
	  	is the <span class="em emphasis">#ubuntu-server</span> IRC channel on <a href="http://freenode.net" class="ulink" title="http://freenode.net">freenode</a>.
          	</p>
	      </li></ul></div>
</div></div>
</div></div>
</div>
<div class="links nextlinks">
<a class="nextlinks-prev" href="firewall.html" title="Firewall">Previous</a><a class="nextlinks-next" href="certificates-and-security.html" title="Certificates">Next</a>
</div>
<div class="clear"></div>
</div>
<div id="pagebottom"></div>
</div></div>
</div>
<div id="footer"><p>The material in this document is available under a free license, see <a href="https://help.ubuntu.com/legal.html">Legal</a> for details.<br>
          For information on contributing see the <a href="https://wiki.ubuntu.com/DocumentationTeam">Ubuntu Documentation Team wiki page</a>.
          To report errors in this serverguide documentation, <a href="https://bugs.launchpad.net/serverguide">file a bug report</a>.</p></div>
</div>
</body>
</html>
